home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / PInterfaces / CodeFragments.p < prev    next >
Encoding:
Text File  |  1998-02-12  |  15.2 KB  |  530 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        CodeFragments.p
  3.  
  4.      Contains:    Public Code Fragment Manager Interfaces.
  5.  
  6.      Version:    Technology:    Mac OS 8.1
  7.                  Release:    Universal Interfaces 3.1
  8.  
  9.      Copyright:    © 1992-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. }
  18. {
  19.    •
  20.    ===========================================================================================
  21.    The Code Fragment Manager API
  22.    =============================
  23. }
  24.  
  25.  
  26. {$IFC UNDEFINED UsingIncludes}
  27. {$SETC UsingIncludes := 0}
  28. {$ENDC}
  29.  
  30. {$IFC NOT UsingIncludes}
  31.  UNIT CodeFragments;
  32.  INTERFACE
  33. {$ENDC}
  34.  
  35. {$IFC UNDEFINED __CODEFRAGMENTS__}
  36. {$SETC __CODEFRAGMENTS__ := 1}
  37.  
  38. {$I+}
  39. {$SETC CodeFragmentsIncludes := UsingIncludes}
  40. {$SETC UsingIncludes := 1}
  41.  
  42. {$IFC UNDEFINED __MACTYPES__}
  43. {$I MacTypes.p}
  44. {$ENDC}
  45. {$IFC UNDEFINED __FILES__}
  46. {$I Files.p}
  47. {$ENDC}
  48.  
  49.  
  50. {$PUSH}
  51. {$ALIGN MAC68K}
  52. {$LibExport+}
  53.  
  54. {
  55.    §
  56.    ===========================================================================================
  57.    General Types and Constants
  58.    ===========================
  59. }
  60.  
  61.  
  62.  
  63. CONST
  64.     kCFragResourceType            = 'cfrg';
  65.     kCFragResourceID            = 0;
  66.     kCFragLibraryFileType        = 'shlb';
  67.     kCFragAllFileTypes            = $FFFFFFFF;
  68.  
  69.  
  70.  
  71. TYPE
  72.     CFragArchitecture                    = OSType;
  73.  
  74. CONST
  75.     kPowerPCCFragArch            = 'pwpc';
  76.     kMotorola68KCFragArch        = 'm68k';
  77.     kAnyCFragArch                = $3F3F3F3F;
  78.  
  79. {$IFC TARGET_CPU_PPC }
  80.     kCompiledCFragArch            = 'pwpc';
  81.  
  82. {$ENDC}  {TARGET_CPU_PPC}
  83.  
  84. {$IFC TARGET_CPU_68K }
  85.     kCompiledCFragArch            = 'm68k';
  86.  
  87. {$ENDC}  {TARGET_CPU_68K}
  88.  
  89.  
  90. TYPE
  91.     CFragVersionNumber                    = UInt32;
  92.  
  93. CONST
  94.     kNullCFragVersion            = 0;
  95.     kWildcardCFragVersion        = $FFFFFFFF;
  96.  
  97.  
  98.  
  99. TYPE
  100.     CFragUsage                            = UInt8;
  101.  
  102. CONST
  103.     kImportLibraryCFrag            = 0;                            {  Standard CFM import library. }
  104.     kApplicationCFrag            = 1;                            {  MacOS application. }
  105.     kDropInAdditionCFrag        = 2;                            {  Application or library private extension/plug-in }
  106.     kStubLibraryCFrag            = 3;                            {  Import library used for linking only }
  107.     kWeakStubLibraryCFrag        = 4;                            {  Import library used for linking only and will be automatically weak linked }
  108.  
  109.  
  110.     kIsCompleteCFrag            = 0;                            {  A "base" fragment, not an update. }
  111.     kFirstCFragUpdate            = 1;                            {  The first update, others are numbered 2, 3, ... }
  112.  
  113.  
  114.     kCFragGoesToEOF                = 0;
  115.  
  116.  
  117.  
  118.  
  119.  
  120. TYPE
  121.     CFragLocatorKind                    = UInt8;
  122.  
  123. CONST
  124.     kMemoryCFragLocator            = 0;                            {  Container is already addressable. }
  125.     kDataForkCFragLocator        = 1;                            {  Container is in a file's data fork. }
  126.     kResourceCFragLocator        = 2;                            {  Container is in a file's resource fork. }
  127.     kByteStreamCFragLocator        = 3;                            {  ! Reserved for possible future use! }
  128.     kNamedFragmentCFragLocator    = 4;                            {  ! Reserved for possible future use! }
  129.  
  130.  
  131. {
  132.    --------------------------------------------------------------------------------------
  133.    A 'cfrg' resource consists of a header followed by a sequence of variable length
  134.    members.  The constant kDefaultCFragNameLen only provides for a legal ANSI declaration
  135.    and for a reasonable display in a debugger.  The actual name field is cut to fit.
  136.    There may be "extensions" after the name, the memberSize field includes them.  The
  137.    general form of an extension is a 16 bit type code followed by a 16 bit size in bytes.
  138.    Only one standard extension type is defined at present, it is used by SOM's searching
  139.    mechanism.
  140. }
  141.  
  142.  
  143.  
  144. TYPE
  145.     CFragUsage1UnionPtr = ^CFragUsage1Union;
  146.     CFragUsage1Union = RECORD
  147.         CASE INTEGER OF
  148.                                                                         {  ! Meaning differs depending on value of "usage". }
  149.         0: (
  150.             appStackSize:        UInt32;                                    {  If the fragment is an application. (Not used by CFM!) }
  151.             );
  152.     END;
  153.  
  154.     CFragUsage2UnionPtr = ^CFragUsage2Union;
  155.     CFragUsage2Union = RECORD
  156.         CASE INTEGER OF
  157.                                                                         {  ! Meaning differs depending on value of "usage". }
  158.         0: (
  159.             appSubdirID:        SInt16;                                    {  If the fragment is an application. }
  160.             );
  161.         1: (
  162.             libFlags:            UInt16;                                    {  If the fragment is an import library. }
  163.             );
  164.     END;
  165.  
  166.  
  167. CONST
  168.                                                                 {  Bit masks for the CFragUsage2Union libFlags variant. }
  169.     kCFragLibUsageMapPrivatelyMask = $0001;                        {  Put container in app heap if necessary. }
  170.  
  171.  
  172. TYPE
  173.     CFragWhere1UnionPtr = ^CFragWhere1Union;
  174.     CFragWhere1Union = RECORD
  175.         CASE INTEGER OF
  176.                                                                         {  ! Meaning differs depending on value of "where". }
  177.         0: (
  178.             spaceID:            UInt32;                                    {  If the fragment is in memory.  (Actually an AddressSpaceID.) }
  179.             );
  180.         1: (
  181.             forkKind:            OSType;                                    {  If the fragment is in an arbitrary byte stream fork. }
  182.             );
  183.     END;
  184.  
  185.     CFragWhere2UnionPtr = ^CFragWhere2Union;
  186.     CFragWhere2Union = RECORD
  187.         CASE INTEGER OF
  188.                                                                         {  ! Meaning differs depending on value of "where". }
  189.         0: (
  190.             forkInstance:        UInt16;                                    {  If the fragment is in an arbitrary byte stream fork. }
  191.             );
  192.     END;
  193.  
  194.  
  195. CONST
  196.     kDefaultCFragNameLen        = 16;
  197.  
  198.  
  199.  
  200. TYPE
  201.     CFragResourceMemberPtr = ^CFragResourceMember;
  202.     CFragResourceMember = RECORD
  203.         architecture:            CFragArchitecture;
  204.         reservedA:                UInt16;                                    {  ! Must be zero! }
  205.         reservedB:                SInt8;                                    {  ! Must be zero! }
  206.         updateLevel:            SInt8;
  207.         currentVersion:            CFragVersionNumber;
  208.         oldDefVersion:            CFragVersionNumber;
  209.         uUsage1:                CFragUsage1Union;
  210.         uUsage2:                CFragUsage2Union;
  211.         usage:                    SInt8;
  212.         where:                    SInt8;
  213.         offset:                    UInt32;
  214.         length:                    UInt32;
  215.         uWhere1:                CFragWhere1Union;
  216.         uWhere2:                CFragWhere2Union;
  217.         extensionCount:            UInt16;                                    {  The number of extensions beyond the name. }
  218.         memberSize:                UInt16;                                    {  Size in bytes, includes all extensions. }
  219.         name:                    PACKED ARRAY [0..15] OF UInt8;            {  ! Actually a sized PString. }
  220.     END;
  221.  
  222.     CFragResourceExtensionHeaderPtr = ^CFragResourceExtensionHeader;
  223.     CFragResourceExtensionHeader = RECORD
  224.         extensionKind:            UInt16;
  225.         extensionSize:            UInt16;
  226.     END;
  227.  
  228.     CFragResourceSearchExtensionPtr = ^CFragResourceSearchExtension;
  229.     CFragResourceSearchExtension = RECORD
  230.         header:                    CFragResourceExtensionHeader;
  231.         libKind:                OSType;
  232.         qualifiers:                SInt8;                                    {  ! Actually four PStrings. }
  233.     END;
  234.  
  235.  
  236. CONST
  237.     kCFragResourceSearchExtensionKind = $30EE;
  238.  
  239.  
  240.  
  241. TYPE
  242.     CFragResourcePtr = ^CFragResource;
  243.     CFragResource = RECORD
  244.         reservedA:                UInt32;                                    {  ! Must be zero! }
  245.         reservedB:                UInt32;                                    {  ! Must be zero! }
  246.         reservedC:                UInt16;                                    {  ! Must be zero! }
  247.         version:                UInt16;
  248.         reservedD:                UInt32;                                    {  ! Must be zero! }
  249.         reservedE:                UInt32;                                    {  ! Must be zero! }
  250.         reservedF:                UInt32;                                    {  ! Must be zero! }
  251.         reservedG:                UInt32;                                    {  ! Must be zero! }
  252.         reservedH:                UInt16;                                    {  ! Must be zero! }
  253.         memberCount:            UInt16;
  254.         firstMember:            CFragResourceMember;
  255.     END;
  256.  
  257.  
  258. CONST
  259.     kCurrCFragResourceVersion    = 1;
  260.  
  261.  
  262.  
  263.  
  264. TYPE
  265.     CFragConnectionID = ^LONGINT;
  266.     CFragClosureID = ^LONGINT;
  267.     CFragContainerID = ^LONGINT;
  268.     CFragContextID = ^LONGINT;
  269.     CFragLoadOptions                    = UInt32;
  270.  
  271. CONST
  272.     kReferenceCFrag                = $0001;                        {  Try to use existing copy, increment reference counts. }
  273.     kFindCFrag                    = $0002;                        {  Try find an existing copy, do not increment reference counts. }
  274.     kPrivateCFragCopy            = $0005;                        {  Prepare a new private copy.  (kReferenceCFrag | 0x0004) }
  275.  
  276.  
  277.     kUnresolvedCFragSymbolAddress = 0;
  278.  
  279.  
  280.  
  281. TYPE
  282.     CFragSymbolClass                    = UInt8;
  283.  
  284. CONST
  285.     kCodeCFragSymbol            = 0;
  286.     kDataCFragSymbol            = 1;
  287.     kTVectorCFragSymbol            = 2;
  288.     kTOCCFragSymbol                = 3;
  289.     kGlueCFragSymbol            = 4;
  290.  
  291.  
  292. {
  293.    §
  294.    ===========================================================================================
  295.    Macros and Functions
  296.    ====================
  297. }
  298.  
  299.  
  300.  
  301. FUNCTION GetSharedLibrary(libName: Str63; archType: CFragArchitecture; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  302.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  303.     INLINE $3F3C, $0001, $AA5A;
  304.     {$ENDC}
  305. FUNCTION GetDiskFragment({CONST}VAR fileSpec: FSSpec; offset: UInt32; length: UInt32; fragName: Str63; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  306.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  307.     INLINE $3F3C, $0002, $AA5A;
  308.     {$ENDC}
  309. FUNCTION GetMemFragment(memAddr: UNIV Ptr; length: UInt32; fragName: Str63; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  310.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  311.     INLINE $3F3C, $0003, $AA5A;
  312.     {$ENDC}
  313. FUNCTION CloseConnection(VAR connID: CFragConnectionID): OSErr;
  314.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  315.     INLINE $3F3C, $0004, $AA5A;
  316.     {$ENDC}
  317. FUNCTION FindSymbol(connID: CFragConnectionID; symName: Str255; VAR symAddr: Ptr; VAR symClass: CFragSymbolClass): OSErr;
  318.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  319.     INLINE $3F3C, $0005, $AA5A;
  320.     {$ENDC}
  321. FUNCTION CountSymbols(connID: CFragConnectionID; VAR symCount: LONGINT): OSErr;
  322.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  323.     INLINE $3F3C, $0006, $AA5A;
  324.     {$ENDC}
  325. FUNCTION GetIndSymbol(connID: CFragConnectionID; symIndex: LONGINT; VAR symName: Str255; VAR symAddr: Ptr; VAR symClass: CFragSymbolClass): OSErr;
  326.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  327.     INLINE $3F3C, $0007, $AA5A;
  328.     {$ENDC}
  329.  
  330. {
  331.    §
  332.    ===========================================================================================
  333.    Initialization & Termination Routines
  334.    =====================================
  335. }
  336.  
  337.  
  338. {
  339.    -----------------------------------------------------------------------------------------
  340.    A fragment's initialization and termination routines are called when a new incarnation of
  341.    the fragment is created or destroyed, respectively.  Exactly when this occurs depends on
  342.    what kinds of section sharing the fragment has and how the fragment is prepared.  Import
  343.    libraries have at most one incarnation per process.  Fragments prepared with option
  344.    kPrivateCFragCopy may have many incarnations per process.
  345.    The initialization function is passed a pointer to an initialization information structure
  346.    and returns an OSErr.  If an initialization function returns a non-zero value the entire
  347.    closure of which it is a part fails.  The C prototype for an initialization function is:
  348.           OSErr    CFragInitFunction    ( const CFragInitBlock *    initBlock );
  349.    The termination procedure takes no parameters and returns nothing.  The C prototype for a
  350.    termination procedure is:
  351.           void    CFragTermProcedure    ( void );
  352.    Note that since the initialization and termination routines are themselves "CFM"-style
  353.    routines whether or not they have the "pascal" keyword is irrelevant.
  354. }
  355.  
  356.  
  357. {
  358.    -----------------------------------------------------------------------------------------
  359.    ! Note:
  360.    ! The "System7" portion of these type names was introduced during the evolution towards
  361.    ! the now defunct Copland version of Mac OS.  Copland was to be called System 8 and there
  362.    ! were slightly different types for System 7 and System 8.  The "generic" type names were
  363.    ! conditionally defined for the desired target system.
  364.    ! Always use the generic types, e.g. CFragInitBlock!  The "System7" names have been kept
  365.    ! only to avoid perturbing code that (improperly) used the target specific type.
  366. }
  367.  
  368.  
  369.  
  370. TYPE
  371.     CFragSystem7MemoryLocatorPtr = ^CFragSystem7MemoryLocator;
  372.     CFragSystem7MemoryLocator = RECORD
  373.         address:                LogicalAddress;
  374.         length:                    UInt32;
  375.         inPlace:                BOOLEAN;
  376.         reservedA:                SInt8;                                    {  ! Must be zero! }
  377.         reservedB:                UInt16;                                    {  ! Must be zero! }
  378.     END;
  379.  
  380.     CFragSystem7DiskFlatLocatorPtr = ^CFragSystem7DiskFlatLocator;
  381.     CFragSystem7DiskFlatLocator = RECORD
  382.         fileSpec:                FSSpecPtr;
  383.         offset:                    UInt32;
  384.         length:                    UInt32;
  385.     END;
  386.  
  387. {  ! This must have a file specification at the same offset as a disk flat locator! }
  388.     CFragSystem7SegmentedLocatorPtr = ^CFragSystem7SegmentedLocator;
  389.     CFragSystem7SegmentedLocator = RECORD
  390.         fileSpec:                FSSpecPtr;
  391.         rsrcType:                OSType;
  392.         rsrcID:                    SInt16;
  393.         reservedA:                UInt16;                                    {  ! Must be zero! }
  394.     END;
  395.  
  396.     CFragSystem7LocatorPtr = ^CFragSystem7Locator;
  397.     CFragSystem7Locator = RECORD
  398.         where:                    SInt32;
  399.         CASE INTEGER OF
  400.         0: (
  401.             onDisk:                CFragSystem7DiskFlatLocator;
  402.             );
  403.         1: (
  404.             inMem:                CFragSystem7MemoryLocator;
  405.             );
  406.         2: (
  407.             inSegs:                CFragSystem7SegmentedLocator;
  408.             );
  409.     END;
  410.  
  411.     CFragSystem7InitBlockPtr = ^CFragSystem7InitBlock;
  412.     CFragSystem7InitBlock = RECORD
  413.         contextID:                CFragContextID;
  414.         closureID:                CFragClosureID;
  415.         connectionID:            CFragConnectionID;
  416.         fragLocator:            CFragSystem7Locator;
  417.         libName:                StringPtr;
  418.         reservedA:                UInt32;                                    {  ! Must be zero! }
  419.     END;
  420.  
  421.     CFragInitBlock                        = CFragSystem7InitBlock;
  422.     CFragInitBlockPtr                     = ^CFragInitBlock;
  423. {  These init/term routine types are only of value to CFM itself. }
  424. {$IFC TYPED_FUNCTION_POINTERS}
  425.     CFragInitFunction = FUNCTION({CONST}VAR initBlock: CFragInitBlock): OSErr; C;
  426. {$ELSEC}
  427.     CFragInitFunction = ProcPtr;
  428. {$ENDC}
  429.  
  430. {$IFC TYPED_FUNCTION_POINTERS}
  431.     CFragTermProcedure = PROCEDURE; C;
  432. {$ELSEC}
  433.     CFragTermProcedure = ProcPtr;
  434. {$ENDC}
  435.  
  436. {
  437.    §
  438.    ===========================================================================================
  439.    Old Name Spellings
  440.    ==================
  441. }
  442.  
  443.  
  444. {
  445.    -------------------------------------------------------------------------------------------
  446.    We've tried to reduce the risk of name collisions in the future by introducing the phrase
  447.    "CFrag" into constant and type names.  The old names are defined below in terms of the new.
  448. }
  449.  
  450.  
  451.  
  452. CONST
  453.     kLoadCFrag                    = $0001;
  454.  
  455.  
  456. {$IFC OLDROUTINENAMES }
  457.  
  458. TYPE
  459.     ConnectionID                        = CFragConnectionID;
  460.     LoadFlags                            = CFragLoadOptions;
  461.     SymClass                            = CFragSymbolClass;
  462.     InitBlock                            = CFragInitBlock;
  463.     InitBlockPtr                         = ^InitBlock;
  464.     MemFragment                            = CFragSystem7MemoryLocator;
  465.     MemFragmentPtr                         = ^MemFragment;
  466.     DiskFragment                        = CFragSystem7DiskFlatLocator;
  467.     DiskFragmentPtr                     = ^DiskFragment;
  468.     SegmentedFragment                    = CFragSystem7SegmentedLocator;
  469.     SegmentedFragmentPtr                 = ^SegmentedFragment;
  470.     FragmentLocator                        = CFragSystem7Locator;
  471.     FragmentLocatorPtr                     = ^FragmentLocator;
  472.     CFragHFSMemoryLocator                = CFragSystem7MemoryLocator;
  473.     CFragHFSMemoryLocatorPtr             = ^CFragHFSMemoryLocator;
  474.     CFragHFSDiskFlatLocator                = CFragSystem7DiskFlatLocator;
  475.     CFragHFSDiskFlatLocatorPtr             = ^CFragHFSDiskFlatLocator;
  476.     CFragHFSSegmentedLocator            = CFragSystem7SegmentedLocator;
  477.     CFragHFSSegmentedLocatorPtr         = ^CFragHFSSegmentedLocator;
  478.     CFragHFSLocator                        = CFragSystem7Locator;
  479.     CFragHFSLocatorPtr                     = ^CFragHFSLocator;
  480.  
  481. CONST
  482.     kPowerPCArch                = 'pwpc';
  483.     kMotorola68KArch            = 'm68k';
  484.     kAnyArchType                = $3F3F3F3F;
  485.     kNoLibName                    = 0;
  486.     kNoConnectionID                = 0;
  487.     kLoadLib                    = $0001;
  488.     kFindLib                    = $0002;
  489.     kNewCFragCopy                = $0005;
  490.     kLoadNewCopy                = $0005;
  491.     kUseInPlace                    = $80;
  492.     kCodeSym                    = 0;
  493.     kDataSym                    = 1;
  494.     kTVectSym                    = 2;
  495.     kTOCSym                        = 3;
  496.     kGlueSym                    = 4;
  497.     kInMem                        = 0;
  498.     kOnDiskFlat                    = 1;
  499.     kOnDiskSegmented            = 2;
  500.     kIsLib                        = 0;
  501.     kIsApp                        = 1;
  502.     kIsDropIn                    = 2;
  503.     kFullLib                    = 0;
  504.     kUpdateLib                    = 1;
  505.     kWholeFork                    = 0;
  506.     kCFMRsrcType                = 'cfrg';
  507.     kCFMRsrcID                    = 0;
  508.     kSHLBFileType                = 'shlb';
  509.     kUnresolvedSymbolAddress    = 0;
  510.  
  511.     kPowerPC                    = 'pwpc';
  512.     kMotorola68K                = 'm68k';
  513.  
  514. {$ENDC}  {OLDROUTINENAMES}
  515.  
  516.  
  517.  
  518.  
  519.  
  520. {$ALIGN RESET}
  521. {$POP}
  522.  
  523. {$SETC UsingIncludes := CodeFragmentsIncludes}
  524.  
  525. {$ENDC} {__CODEFRAGMENTS__}
  526.  
  527. {$IFC NOT UsingIncludes}
  528.  END.
  529. {$ENDC}
  530.